array-tools

array-tools

Lightweight tool-kit for working with array data. 1.5k, compressed.

> var a = require("array-tools");

There are four ways to use it.

1. As a standard library, passing the input array on each method invocation:

> var remainder = a.without([ 1, 2, 3, 4, 5 ], 1)
> a.exists(remainder, 1)
false

1. As a chainable method, passing the input array once then chaining from there:

> a([ 1, 2, 3, 4, 5 ]).without(1).exists(1);
false

1. As a base class.

var util = require("util");
var ArrayTools = require("array-tools");

function CarCollection(cars){
  ArrayTools.call(this, cars);
}
util.inherits(CarCollection, ArrayTools);

var cars = new CarCollection([ 
  { owner: "Me", model: "Citreon Xsara" }, 
  { owner: "Floyd", model: "Bugatti Veyron" } 
]);

cars.findWhere({ owner: "Floyd" });
// returns { owner: "Floyd", model: "Bugatti Veyron" }

1. As a command-line tool.

$ curl -s "https://api.github.com/users/75lb/repos?page=1&per_page=100" | array-tools pick full_name description
[
  {
    "full_name": "75lb/ansi-escape-sequences",
    "description": "A simple library containing all known terminal ansi escape codes and sequences."
  },
  {
    "full_name": "75lb/baldrick",
    "description": "Your own private dogsbody. Does the shitty work you can't be arsed to do."
  },
  etc,
  etc
]

More on chaining

Each method returning an Array (e.g. where, without) can be chained. Methods not returning an array (exists, contains) cannot be chained. If the final operation in your chain is chainable (returns an array), append .val() to terminate the chain and retrieve the output.

> a([ 1, 2, 2, 3 ]).exists(1)
true
> a([ 1, 2, 2, 3 ]).without(1).exists(1)
false
> a([ 1, 2, 2, 3 ]).without(1).unique().val()
[ 2, 3 ]

Compatibility

This library is tested in node versions 0.10, 0.11, 0.12, iojs and the following browsers:

Install

As a library:

$ npm install array-tools --save

As a command-line tool:

$ npm install -g array-tools

API Reference

• array-tools
  • chainable
    • .arrayify(any) ⇒ Array
    • .where(arrayOfObjects, query) ⇒ Array
    • .pluck(arrayOfObjects, ...property) ⇒ Array
    • .pick(arrayOfObjects, ...property) ⇒ Array.<object>
    • .without(array, toRemove) ⇒ Array
    • .union(array1, array2, idKey) ⇒ Array
    • .commonSequence(a, b) ⇒ Array
    • .unique(array) ⇒ Array
    • .spliceWhile(array, index, test, ...elementN) ⇒ Array
    • .extract(array, query) ⇒ Array
    • .flatten(array) ⇒ Array
    • .sortBy(arrayOfObjects, columns, customOrder) ⇒ Array
  • not chainable
    • .exists(array, value) ⇒ boolean
    • .findWhere(arrayOfObjects, query) ⇒ object
    • .last(arr) ⇒ *
    • .remove(arr, toRemove) ⇒ *
    • .contains(arr, value) ⇒

a.arrayify(any) ⇒ Array

Takes any input and guarantees an array back.

• converts array-like objects (e.g. arguments) to a real array
• converts null or undefined to an empty array
• converts any another other, singular value into an array containing that value
• ignores input which is already an array

Kind: static method of array-tools
Category: chainable

Param	Type	Description
any	*	the input value to convert to an array

Example

> a.arrayify(null)
[]

> a.arrayify(0)
[ 0 ]

> a.arrayify([ 1, 2 ])
[ 1, 2 ]

> function f(){ return a.arrayify(arguments); }
> f(1,2,3)
[ 1, 2, 3 ]

a.where(arrayOfObjects, query) ⇒ Array

Query a recordset, at any depth..

Kind: static method of array-tools
Category: chainable

Param	Type	Description
arrayOfObjects	Array.<object>	the recordset to query
query	query	the query definition

Example

> data = [
    { name: "Dana", age: 30 },
    { name: "Yana", age: 20 },
    { name: "Zhana", age: 10 }
]

> // match on an exact value
> a.where(data, { age: 10 })
[ { name: 'Zhana', age: 10 } ]

> // match records which satisfy the function testing the value of the `age` field
> a.where(data, { age: function(ageValue){ return ageValue > 10; }  })
[ { name: 'Dana', age: 30 }, { name: 'Yana', age: 20 } ]

> // match if NOT the value
> a.where(data, { "!age": 10 })
[ { name: 'Dana', age: 30 }, { name: 'Yana', age: 20 } ]

> // match on regular expression
> a.where(data, { name: /ana/ })
[ { name: 'Dana', age: 30 },
  { name: 'Yana', age: 20 },
  { name: 'Zhana', age: 10 } ]

> // you can perform deep queries 
> deepData = [
    { name: "Dana", favourite: { colour: "light red" } },
    { name: "Yana", favourite: { colour: "dark red" } },
    { name: "Zhana", favourite: { colour: [ "white", "red" ] } }
]

> // match values of `person.favourite.colour` which match the regex `/red/`
> a.where(deepData, { favourite: { colour: /red/ } })
[ { name: 'Dana', favourite: { colour: 'light red' } },
  { name: 'Yana', favourite: { colour: 'dark red' } } ]

> // if there are one or more values for colour (i.e. the field may contain a singular
> // or array of values) then search inside arrays too 
> a.where(deepData, { favourite: { "+colour": /red/ } })
[ { name: 'Dana', favourite: { colour: 'light red' } },
  { name: 'Yana', favourite: { colour: 'dark red' } },
  { name: 'Zhana', favourite: { colour: [ "white", "red" ] } } ]

a.pluck(arrayOfObjects, ...property) ⇒ Array

Plucks the value of the specified property from each object in the input array

Kind: static method of array-tools
Category: chainable

Param	Type	Description
arrayOfObjects	Array.<object>	The input recordset
...property	string	Up to three property names - the first one found will be returned.

Example

> var data = [
    { a: "Lionel", b: "Roger" },
    { a: "Luis", b: "Craig" },
    { b: "Peter" },
]

> a.pluck(data, "a")
[ 'Lionel', 'Luis' ]

> a.pluck(data, "a", "b")
[ 'Lionel', 'Luis', 'Peter' ]

a.pick(arrayOfObjects, ...property) ⇒ Array.<object>

return a copy of the input arrayOfObjects containing objects having only the cherry-picked properties

Kind: static method of array-tools
Category: chainable

Param	Type	Description
arrayOfObjects	Array.<object>	the input
...property	string	the properties to include in the result

Example

> data = [
    { name: "Dana", age: 30 },
    { name: "Yana", age: 20 },
    { name: "Zhana", age: 10 }
]

> a.pick(data, "name")
[ { name: 'Dana' }, { name: 'Yana' }, { name: 'Zhana' } ]

> a.pick(data, "name", "age")
[ { name: 'Dana', age: 30 },
  { name: 'Yana', age: 20 },
  { name: 'Zhana', age: 10 } ]

a.without(array, toRemove) ⇒ Array

Returns the input minus the specified values.

Kind: static method of array-tools
Category: chainable

Param	Type	Description
array	Array	the input array
toRemove	*	a single, or array of values to omit

Example

> a.without([ 1, 2, 3 ], 2)
[ 1, 3 ]

> a.without([ 1, 2, 3 ], [ 2, 3 ])
[ 1 ]

a.union(array1, array2, idKey) ⇒ Array

merge two arrays into a single array of unique values

Kind: static method of array-tools
Category: chainable

Param	Type	Description
array1	Array	First array
array2	Array	Second array
idKey	string	the unique ID property name

Example

> var array1 = [ 1, 2 ], array2 = [ 2, 3 ];
> a.union(array1, array2)
[ 1, 2, 3 ]

> var array1 = [ { id: 1 }, { id: 2 } ], array2 = [ { id: 2 }, { id: 3 } ];
> a.union(array1, array2)
[ { id: 1 }, { id: 2 }, { id: 3 } ]

> var array2 = [ { id: 2, blah: true }, { id: 3 } ]
> a.union(array1, array2)
[ { id: 1 },
  { id: 2 },
  { id: 2, blah: true },
  { id: 3 } ]
> a.union(array1, array2, "id")
[ { id: 1 }, { id: 2 }, { id: 3 } ]

a.commonSequence(a, b) ⇒ Array

Returns the initial elements which both input arrays have in common

Kind: static method of array-tools
Category: chainable

Param	Type	Description
a	Array	first array to compare
b	Array	second array to compare

Example

> a.commonSequence([1,2,3], [1,2,4])
[ 1, 2 ]

a.unique(array) ⇒ Array

returns an array of unique values

Kind: static method of array-tools
Category: chainable

Param	Type	Description
array	Array	input array

Example

> n = [1,6,6,7,1]
[ 1, 6, 6, 7, 1 ]

> a.unique(n)
[ 1, 6, 7 ]

a.spliceWhile(array, index, test, ...elementN) ⇒ Array

splice from index until test fails

Kind: static method of array-tools
Category: chainable

Param	Type	Description
array	Array	the input array
index	number	the position to begin splicing from
test	RegExp	the test to continue splicing while true
...elementN	*	the elements to add to the array

Example

> letters = ["a", "a", "b"]
[ 'a', 'a', 'b' ]

> a.spliceWhile(letters, 0, /a/, "x")
[ 'a', 'a' ]

> letters
[ 'x', 'b' ]

a.extract(array, query) ⇒ Array

Removes items from array which satisfy the query. Modifies the input array, returns the extracted.

Kind: static method of array-tools
Returns: Array - the extracted items.
Category: chainable

Param	Type	Description
array	Array	the input array, modified directly
query	function | object	Per item in the array, if either the function returns truthy or the exists query is satisfied, the item is extracted

a.flatten(array) ⇒ Array

flatten an array of arrays into a single array

Kind: static method of array-tools
Category: chainable
Since: 1.4.0

Param	Type	Description
array	Array	the input array

Example

> numbers = [ 1, 2, [ 3, 4 ], 5 ]
> a.flatten(numbers)
[ 1, 2, 3, 4, 5 ]

a.sortBy(arrayOfObjects, columns, customOrder) ⇒ Array

Sort an array of objects by one or more fields

Kind: static method of array-tools
Category: chainable
Since: 1.5.0

Param	Type	Description
arrayOfObjects	Array.<object>	input array
columns	string | Array.<string>	column name(s) to sort by
customOrder	object	specific sort orders, per columns

Example

>  var fixture = [
    { a: 4, b: 1, c: 1},
    { a: 4, b: 3, c: 1},
    { a: 2, b: 2, c: 3},
    { a: 2, b: 2, c: 2},
    { a: 1, b: 3, c: 4},
    { a: 1, b: 1, c: 4},
    { a: 1, b: 2, c: 4},
    { a: 3, b: 3, c: 3},
    { a: 4, b: 3, c: 1}
];
> a.sortBy(fixture, ["a", "b", "c"])
[ { a: 1, b: 1, c: 4 },
  { a: 1, b: 2, c: 4 },
  { a: 1, b: 3, c: 4 },
  { a: 2, b: 2, c: 2 },
  { a: 2, b: 2, c: 3 },
  { a: 3, b: 3, c: 3 },
  { a: 4, b: 1, c: 1 },
  { a: 4, b: 3, c: 1 },
  { a: 4, b: 3, c: 1 } ]

a.exists(array, value) ⇒ boolean

returns true if a value, or nested object value exists in an array

Kind: static method of array-tools
Category: not chainable

Param	Type	Description
array	Array	the array to search
value	*	the value to search for

Example

> a.exists([ 1, 2, 3 ], 2)
true

> a.exists([ { result: false }, { result: false } ], { result: true })
false

> a.exists([ { result: true }, { result: false } ], { result: true })
true

> a.exists([ { result: true }, { result: true } ], { result: true })
true

a.findWhere(arrayOfObjects, query) ⇒ object

returns the first item from arrayOfObjects where key/value pairs from query are matched identically

Kind: static method of array-tools
Category: not chainable

Param	Type	Description
arrayOfObjects	Array.<object>	the array to search
query	object	an object containing the key/value pairs you want to match

Example

> dudes = [{ name: "Jim", age: 8}, { name: "Clive", age: 8}, { name: "Hater", age: 9}]
[ { name: 'Jim', age: 8 },
  { name: 'Clive', age: 8 },
  { name: 'Hater', age: 9 } ]

> a.findWhere(dudes, { age: 8})
{ name: 'Jim', age: 8 }

a.last(arr) ⇒ *

Return the last item in an array.

Kind: static method of array-tools
Category: not chainable
Since: 1.7.0

Param	Type	Description
arr	Array	the input array

a.remove(arr, toRemove) ⇒ *

Kind: static method of array-tools
Category: not chainable
Since: 1.8.0

Param	Type	Description
arr	Array	the input array
toRemove	*	the item to remove

a.contains(arr, value) ⇒

Searches the array for the exact value supplied (strict equality). To query for value existance using an expression or function, use exists.

Kind: static method of array-tools
Returns: boolean
Category: not chainable
Since: 1.8.0

Param	Type	Description
arr	Array	the input array
value	*	the value to look for

---

© 2015 Lloyd Brookes [e-mail]. Documented by jsdoc-to-markdown.